Skip to content

refactor(agents): slim agent_scope and purge _ACTION_SCOPE_STOPWORDS for typed scope matching - #8936

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/agent-scope-slim-20261117
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/agent-scope-slim-20261117

Conversation

@loopx-agent

@loopx-agent loopx-agent commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Rebases onto origin/main (0514512ee7), slims loopx/control_plane/agents/agent_scope.py (1,453 -> 1,155 lines, -298 net LOC; any_count: 13, dict_any_count: 0), completely deletes _ACTION_SCOPE_STOPWORDS and _action_scope_tokens_from_text, and replaces prose stopword token-bag matching in loopx/control_plane/quota/_supporting_projections.py with typed structured scope matching (with CJK-safe exact phrase matching only when a lesson carries no structured target fields).

Key Changes

  • loopx/control_plane/agents/agent_scope.py (1,453 -> 1,155 lines, 573+/871- vs origin/main, -298 net LOC; any_count: 107 -> 13; dict_any_count: 0):
    • Deleted _ACTION_SCOPE_STOPWORDS, _action_scope_tokens_from_text, and unused import re (zero prose stopword tokenizers remain in agent_scope.py).
    • Slimmed and deduplicated frontier/fallback candidate builders via typed helper primitives (_TodoPatch, _as_dict, _int_value, _dict_items, _first_dict, _todo_label, _todo_identity, _sorted_claimants, _collect_lane_or_fallback, _select_and_compact_candidates, _blocking_handoff_copy).
    • Kept all 10 registered vocabulary_v0.json frontier producer names intact and removed 5 single-line/unused internal wrappers.
  • loopx/canary/module_metric_baseline.json:
    • Tightened "loopx/control_plane/agents/agent_scope.py" "any_count" from 107 to 13 (keeping "dict_any_count": 0).
  • loopx/control_plane/quota/_supporting_projections.py, should_run_packet.py, loopx/feedback.py, loopx/control_plane/runtime/run_compaction.py:
    • Replaced _action_scope_tokens_from_text stopword bag overlap in _reward_lesson_projection_warning with _SelectionScopeContext, _extract_selection_scope_context, _match_lesson_structured_scope, and _match_unstructured_avoid.
    • Retained optional structured scope fields (todo_id, todo_ids, claimed_by, agent_id, task_class, capability_id, capability_ids, required_capabilities, work_lane, action_kind, target_key, scope_key, scope_keys, target_scopes, decision_scope) through compact_reward_lesson and compact_human_reward.
    • _reward_lesson_projection_warning now matches strictly on declared structured scope fields (match_kind: "structured_scope") and never falls back to English stopword-bag overlap; unstructured lessons require exact key match or CJK/English normalized phrase containment (rejecting bare [P0..P4] tags).
  • Tests (tests/control_plane/test_quota_supporting_projections.py, tests/control_plane/test_scoped_gate_fallback_selection.py):
    • Added negative English stopword non-overlap checks, CJK exact-phrase checks, CJK structured scope isolation tests (claimed_by, todo_id, task_class), end-to-end build_quota_should_run CJK projection test, and build_agent_scope_frontier_payload CJK fallback test without prose stopwords.

Verification

  • rg -n "_ACTION_SCOPE_STOPWORDS|_action_scope_tokens_from_text" loopx/ tests/ examples/ — 0 hits
  • uv run --extra test ruff check loopx/control_plane/agents/ loopx/control_plane/quota/_supporting_projections.py loopx/control_plane/quota/should_run_packet.py loopx/feedback.py loopx/control_plane/runtime/run_compaction.py tests/control_plane/test_quota_supporting_projections.py tests/control_plane/test_scoped_gate_fallback_selection.py — All checks passed!
  • uv run --extra test mypy — Success: no issues found in 17 source files
  • uv run --extra test mypy --no-incremental --follow-imports=silent loopx/control_plane/agents/agent_scope.py loopx/control_plane/quota/_supporting_projections.py loopx/control_plane/runtime/run_compaction.py — Success: no issues found in 3 source files
  • uv run --extra test python -m pytest tests/architecture/test_semantic_bindings.py tests/architecture/test_semantic_production.py tests/architecture/test_semantic_vocabulary_drift.py tests/control_plane/test_frontier_envelope_compatibility.py tests/control_plane/test_scheduler_backoff_convergence.py tests/control_plane/test_scoped_gate_fallback_selection.py tests/control_plane/test_agent_scope_frontier_contract.py tests/control_plane/test_resume_planning_projection.py tests/control_plane/test_complete_turn_decision.py tests/control_plane/test_quota_supporting_projections.py tests/control_plane/test_work_lane_contract_core.py tests/canary/test_maintainability_ratchet.py -q — 408 passed in 153.07s
  • Isolated HOME uv run --extra test loopx check --scan-path ... — errors=0, public boundary scan clean: 8 files
  • Isolated HOME uv run --extra test loopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick --no-progress — status: passed, merge_gate_passed: true (6/6 direct checks, 3/3 catalog canaries)
  • uv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD — RFC bilingual diff check passed.

@loopx-agent
loopx-agent force-pushed the codex/agent-scope-slim-20261117 branch from 32ecdce to 7e12a36 Compare November 17, 2026 17:40
@loopx-agent loopx-agent changed the title refactor(agents): slim agent_scope, deduplicate candidate/hint builders, and tighten any_count ceiling refactor(agents): slim agent_scope and purge _ACTION_SCOPE_STOPWORDS for typed scope matching Nov 17, 2026
@loopx-agent
loopx-agent force-pushed the codex/agent-scope-slim-20261117 branch from 7e12a36 to 4add4de Compare November 17, 2026 18:16

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent | self_reported | Gemini | Google DeepMind

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

动机 / Motivation

使用 scoped gate 兜底选择、奖惩经验匹配与 Agent 范围收敛的控制面开发者及自动巡检任务。
此前 agent_scope.py 中存在 _ACTION_SCOPE_STOPWORDS 与 _action_scope_tokens_from_text 文本正则停用词黑箱切词启发式(外加大量 dict[str, Any]),维护脆弱且易受多语言或无意义词汇误匹配影响(agent_scope.py 原达 1,453 行、any_count=107);本次彻底清除正则停用词黑箱与 import re,改为基于结构化作用域字段(HUMAN_REWARD_LESSON_STRUCTURED_SCOPE_FIELDS + work_lane)匹配,并同步净化 agent_scope.py 净减 298 行且把 any_count 上限由 107 压低至 13。
删除 _ACTION_SCOPE_STOPWORDS 与 _action_scope_tokens_from_text 及 import re,将反馈经验作用域收口到结构化字段(含 CJK 覆盖测试),同步下调 module_metric_baseline 中 agent_scope.py any_count 至 13。
非目标边界:本 PR 不修改其他文件中的非 scope 停用词残留(由独立 PR 跟进),也不改变无关配额调度策略。

清掉正则停用词启发式不仅消除英文词袋对中文或跨域名场景的盲区,还借助统一辅助提取让 agent_scope.py 实现净减法重构并大幅收敛类型不确定性。

改动思路 / Approach

以显式结构化作用域字段契约(HUMAN_REWARD_LESSON_STRUCTURED_SCOPE_FIELDS 与 work_lane)取代 agent_scope.py 内脆弱的停用词词袋与正则切词,在保持既有公开投影消费契约的同时消减 298 行冗余与 94 个 Any 注解。
当前 PR 边界:仅覆盖 agent_scope.py 停用词退役与结构化投影重构、feedback.py 结构化 lesson 作用域压缩、quota/_supporting_projections.py 与 should_run_packet work_lane 透传及对应 baseline/测试(8 文件)。

  • 结构化匹配不变量:feedback.py 中的 compact_reward_lesson 显式保留与校验结构化 scope 字段(todo_id, agent_id, capability_id, work_lane 等),_supporting_projections.py 优先依据结构化字段交集做经验匹配,消除对自由文本停用词词包的依赖。
  • 类型与体积棘轮:在 agent_scope.py 用 Mapping[str, object] 与共享辅助替代泛滥 dict[str, Any](1,453 -> 1,155 行,import re 彻底删除),同步把 module_metric_baseline.json 中该模块 any_count 上限由 107 锁定下调至 13。

具体改动 / Changes

依据规范 docs/architecture/rfcs/controller-executor-unified-contract-v0.md(修订 ef099ae3ac3c08054b9d928fff48aefe2615b950)核对两项要求:

  • TYPED-SCOPE-MATCH:移除 _ACTION_SCOPE_STOPWORDS 正则停用词启发式,改用结构化作用域与显式分词比较并覆盖 CJK 用例(由 tests/control_plane/test_quota_supporting_projections.py 与 test_scoped_gate_fallback_selection.py 31 passed 验证)。
  • RATCHET-ANY-DOWN:agent_scope.py 净减 298 行并将 module_metric_baseline.json any_count 下调至 13(由 canary premerge 中 control-plane-maintainability-ratchet-smoke.py 验证 PASS)。

关键代码讲解

  1. loopx/control_plane/agents/agent_scope.py:1:彻底移除 import re、_ACTION_SCOPE_STOPWORDS 词袋及 _action_scope_tokens_from_text,整理 _as_dict/_dict_items/_select_and_compact_candidates 与 _AgentScopeNoCandidateContext 结构,单文件净减 298 行、移除 94 个 Any。
  2. loopx/feedback.py:205(HUMAN_REWARD_LESSON_STRUCTURED_SCOPE_FIELDS / compact_reward_lesson):新增结构化 scope 白名单与公开安全校验,确保结构化字段写入即可安全投影消费。
  3. loopx/control_plane/quota/_supporting_projections.py:1(_match_lesson_structured_scope)& should_run_packet.py:1653:把 work_lane 透传至投影并优先匹配结构化域键值,非结构化文本回退收窄为纯显式对比。

对主干的风险 / Risks

历史持久化中若存在完全缺少结构化字段的旧 lesson,_match_unstructured_avoid 仍留有最小只读规范化兜底且有 CJK/ASCII 回归单测保护;另注意后续合并需留意本 PR 与独立 feedback.py 惰性加载改进 PR 分别修改不同行区段(feedback.py:205+ 与顶部 import 区),彼此无语义冲突。远端 GitHub Actions kernel-static-checks 目前报错为 origin/main 既有的 tests/control_plane/test_contract_health.py:10 F401(本 PR 未改该文件)。

验证项 级别 结果 实跑输出(exact head 4add4dec055f0d1adea211ef724c4bfe02706927)
pytest -q tests/control_plane/test_quota_supporting_projections.py tests/control_plane/test_scoped_gate_fallback_selection.py required PASS 31 passed in 7.35s
ruff check loopx/control_plane/agents/agent_scope.py loopx/control_plane/quota/_supporting_projections.py loopx/feedback.py loopx/control_plane/quota/should_run_packet.py required PASS All checks passed!
loopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick required PASS selected_checks: 3, failures: 0, ok: true (maintainability-ratchet + semantic-vocabulary-drift + configure-goal)
远端 GitHub Checks(kernel-static-checks 等) diagnostic (required=false) FAIL (unrelated) 基线 tests/control_plane/test_contract_health.py:10 F401 预存故障

我的整体评价 / Verdict

对精确 head 4add4dec055f0d1adea211ef724c4bfe02706927 的评价:用户体验维度影响为 not_applicable(仅调整控制面内部 scope/projection 结构化匹配逻辑与注解类型,不涉及 UI 界面、样式或渲染视图(inspected: loopx/control_plane/agents/agent_scope.py, loopx/feedback.py)。,unverified_scope: none),长程稳定性 improved。本 PR 在语义对齐侧于 feedback.py 内定义本地结构化 scope 字段元组 HUMAN_REWARD_LESSON_STRUCTURED_SCOPE_FIELDS(semantic_alignment=new_semantics_justified / local_only,未扩充全局 status enum;无兼容旧停用词分支 compatibility_assessment=not_applicable)。经精确 head 本地 Pytest 31 项、ruff 与 maintainability-ratchet/semantic-vocabulary canary 实测全绿,同意合入。

English verdict: APPROVE

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · gpt-6.2-sol · OpenAI · runtime_reported · xhigh
Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

动机 / Motivation

依赖反馈经验选择下一步的 Agent,以及检查 Agent 路线与候选任务的维护者。 旧投影只遍历 avoid 规则并使用英文词袋关联决定,容易跨主题误报;只提供 prefer 的记录不会成为避免提示。 同一份只含 prefer 的正向经验,在基线不会告警。当前头通过实际 quota 决策后生成一条 avoid 警告,Markdown 将原本鼓励的“验证发布清单”显示为应避开的动作,并引导换路线或修改 Todo。两边选中的 Todo 和 should_run 相同。 新投影保留作用域字段,优先按结构化目标匹配,其余保留精确短语兼容分支,并重用既有 frontier 选择和压缩。 当前出入口为原 agent frontier、反馈经验记录、quota 决策及 Markdown 提示。权限授予、执行和持久任务状态仍由现有流程负责。

改动思路 / Approach

保留既有 agent_scope 和 quota 投影的责任,经验方向由原 human_reward 的 avoid/prefer 字段表达,作用域只缩小适用范围。 本提案把 frontier 候选重构与经验读写、压缩和 quota 提示一起修改,后者需要在完整决策和展示入口验证。 合并候选去重和公共压缩可以独立维持。结构化结果优于旧分词,证据显示作用域对/错事例可按预期区别。遇到没有避免建议的经验时仍要保留原方向。

具体改动 / Changes

逐项检查当前头 4add4de 和 merge base 421aa77,8 个文件,+1314/-918。REWARD-WARNING-AVOID 有可复现缺口。TYPED-SCOPE-MATCH 通过同 Todo 有 avoid 和不同 Todo 反事实。FRONTIER-COMPAT 以原 gate、frontier 和 vocabulary 套件验证。 评审依据为 421aa77。 目标规范

关键代码讲解

  • _select_and_compact_candidates 和 _collect_lane_or_fallback 合并候选排序、排除和回退。_TodoPatch 为候选补丁提供集中定义,module ratchet 随 Any 数量下调。准确头 frontier、fallback、gate 队列和原 vocabulary 套件通过。 Agent 选择
  • compact_reward_lesson 和 compact_human_reward 保留公开安全的作用域,并依旧分别保存 avoid、prefer。原记录仍可只保留其中一方。 反馈压缩 运行压缩
  • _attach_quota_supporting_projections 将选中 Todo、lane 和当前身份交给 _reward_lesson_projection_warning。结构化分支在没有 avoid 时把 summary 当 avoid,原 Markdown 消费者按 avoid 渲染,同时保留原任务准入结果。 告警入口

对主干的风险 / Risks

[P2] 保留 prefer 与 avoid 的反馈方向。 同一份只含 prefer 的正向经验,在基线不会告警。当前头通过实际 quota 决策后生成一条 avoid 警告,Markdown 将原本鼓励的“验证发布清单”显示为应避开的动作,并引导换路线或修改 Todo。两边选中的 Todo 和 should_run 相同。 结构化匹配决定哪些真实 avoid 规则适用。只有存在非空 avoid 时才发 warning。保留 prefer 原含义,加一组只含 prefer 的有作用域经验及同 Todo 的 avoid 正例。 这条提示会进入真实的 quota Markdown。虽然不会撤销当前租约,它会把维护者认可的操作交给 Agent 当作改变路线的理由。

五组对照中,已有 avoid 的同 Todo 与纯文本历史经验都正确告警,当前头对其他 Todo 的同文案消除了基线误报。完全没有经验的请求,两边都不产生告警,任务选择与 should_run 保持一致。 准确头 408 项 Python 测试通过,涉及八个改动文件的可执行路径在 quick premerge 通过六项直接检查及三项 canary。七个 Python 源码和测试文件 Ruff 通过。 验证通过源代码的 quota 决策与 CLI Markdown renderer,使用合成公开安全的反馈。未运行远端 CI 或已安装宿主。

我的整体评价 / Verdict

请求修改。保留既有 agent_scope 和 quota 投影的责任,经验方向由原 human_reward 的 avoid/prefer 字段表达,作用域只缩小适用范围。 本提案把 frontier 候选重构与经验读写、压缩和 quota 提示一起修改,后者需要在完整决策和展示入口验证。 需让 reward_lesson_projection_warning 只表达现有的 avoid 规则。 可保留现有 typed scope 重构,再以原生产入口的正负对照验收。 当前变更没有布局变动,同一 Markdown 开关比较了实际输出。

English verdict: REQUEST_CHANGES at 4add4de. A matching prefer-only lesson is emitted as an avoid warning and a route-change instruction. The existing positive and scope-isolation cases pass.

"decision": lesson.get("decision"),
"kind": lesson.get("kind"),
"summary": lesson.get("summary"),
"avoid": avoid_values[0] if avoid_values else str(lesson.get("summary") or ""),

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 保留 prefer 与 avoid 的反馈方向。同一份只含 prefer 的正向经验,在基线不会告警。当前头通过实际 quota 决策后生成一条 avoid 警告,Markdown 将原本鼓励的“验证发布清单”显示为应避开的动作,并引导换路线或修改 Todo。两边选中的 Todo 和 should_run 相同。 结构化匹配决定哪些真实 avoid 规则适用。只有存在非空 avoid 时才发 warning。保留 prefer 原含义,加一组只含 prefer 的有作用域经验及同 Todo 的 avoid 正例。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant